Crate serde_buf

source ·
Expand description

Generic buffering for serde.

This library provides the Owned and Ref types as format-independent buffers for serde. Buffers are guaranteed to serialize in exactly the same way as their original source.

Getting an owned buffer

Any type that implements serde::Serialize can be buffered into an Owned buffer:

use serde_buf::Owned;

// Imagine we have some owned resource...
thread_local! {
    static SOME_THREAD_STATIC: RefCell<Option<Owned>> = RefCell::new(None);
}

// ...and some short-lived data
let short_lived: &'_ str = "A string";

// We can create an owned buffer from it...
let buffer = Owned::buffer(short_lived)?;

// ...and stash it in our owned resource
SOME_THREAD_STATIC.with(|ts| *ts.borrow_mut() = Some(buffer));

Getting a borrowed buffer

Borrowed Ref buffers may have internally borrowed strings, which makes them incompatible with serde::Serialize. You can construct a Ref manually from any underlying source:

use serde_buf::Ref;

// Imagine we have some borrowed datatype
struct MyData<'a> {
    id: u64,
    content: &'a str,
}

// We can buffer it into a partially owned buffer manually
fn buffer_my_data<'a>(data: &'_ MyData<'a>) -> Ref<'a> {
    Ref::record_struct("MyData", [
        ("id", Ref::u64(data.id)),
        ("content", Ref::str(data.content)),
    ])
}

Serializing a buffer

Once you’ve got an Owned or Ref buffer, you can then later use their own serde::Serialize implementations to encode in some format:

#[derive(Serialize)]
struct MyData<'a> {
    id: u64,
    content: &'a str,
}

let data = MyData {
    id: 42,
    content: "Some content",
};

let buffer = Owned::buffer(&data)?;

let data_json = serde_json::to_string(&data)?;
let buffer_json = serde_json::to_string(&buffer)?;

assert_eq!(data_json, buffer_json);

Deserializing from a buffer

Values can also be deserialized directly from an Owned or Ref buffer through their serde::de::IntoDeserializer implementations:

#[derive(Deserialize, Debug, PartialEq)]
struct MyData<'a> {
    id: u64,
    content: &'a str,
}

let data = MyData {
    id: 42,
    content: "Some content",
};

let buffer: Ref = buffer_my_data(&data);

let deserialized = MyData::deserialize(buffer.into_deserializer())?;

assert_eq!(data, deserialized);

Deserializing directly to a buffer

The Ref and Owned types don’t implement serde::Deserialize and can’t be deserialized directly. This is because serde relies on hints from the target type to know how to interpret enum variants. If a type implements both serde::Serialize and serde::Deserialize then you can first deserialize to that concrete type, and then buffer it:

#[derive(Serialize, Deserialize)]
enum MyData<'a> {
    Short(&'a str),
    Full { id: u64, content: &'a str },
}

let json = data_json();

let buffer = Owned::buffer(&serde_json::from_str::<MyData>(&json)?)?;

Structs